by smallnest

godotenv 库介绍

godotenv 是一个 Go 语言库,用于从 .env 文件加载环境变量到应用程序中 1 。它是 Ruby dotenv 项目的 Go 移植版本 1 。

背景

该库遵循十二要素应用方法论,将配置与代码分离。核心理念是:任何可能在部署环境之间变化的内容(如数据库资源句柄或外部服务凭证)都应该从代码中提取到环境变量中。

但在开发机器或运行多个项目的持续集成服务器上设置环境变量并不总是实用的。godotenv 在环境启动时从 .env 文件加载变量到 ENV 中。

安装方法

作为库使用

1
go get github.com/joho/godotenv

作为命令行工具

Go >= 1.17:

1
go install github.com/joho/godotenv/cmd/godotenv@latest

使用方法

基本用法

  1. 在项目根目录创建 .env 文件:
1
2
S3_BUCKET=YOURS3BUCKET
SECRET_KEY=YOURSECRETKEYGOESHERE
  1. 在 Go 代码中加载:
1
2
3
4
5
err := godotenv.Load()
if err != nil {
    log.Fatal("Error loading .env file")
}
s3Bucket := os.Getenv("S3_BUCKET")

自动加载

使用 autoload 包可以在导入时自动读取 .env:

1
import _ "github.com/joho/godotenv/autoload"

加载多个文件

可以指定多个 .env 文件:

1
2
godotenv.Load("somerandomfile")
godotenv.Load("filenumberone.env", "filenumbertwo.env")

核心函数

  • Load(): 加载变量到系统环境,不覆盖已存在的变量
  • Overload(): 加载变量到系统环境,会覆盖已存在的变量
  • Read(): 读取变量到 map 而不是环境变量，会合并多个文件的内容到一个 map 中，后加载的文件会覆盖前面文件中的同名键。
  • Parse(): 从 io.Reader 解析
  • Unmarshal(): 从字符串解析
  • Write(): 将 map 写入文件
  • Marshal(): 将 map 转换为字符串

命令行模式

1
godotenv -f /some/path/to/.env some_command with some args

使用 -o 标志可以覆盖现有环境变量 。

支持的 .env 文件格式

支持注释和 export 语句:

1
2
3
4
# 注释
SOME_VAR=someval
FOO=BAR # 行尾注释
export BAR=BAZ

也支持 YAML 风格:

1
2
FOO: bar
BAR: baz

重要注意事项

优先级规则

已存在的环境变量优先于后加载的变量。这意味着:

  • Load() 不会覆盖已存在的环境变量
  • Overload() 会覆盖已存在的环境变量

多环境管理

推荐的多环境管理方式(开发、测试、生产):

1
2
3
4
5
6
7
8
9
10
11
env := os.Getenv("FOO_ENV")
if "" == env {
  env = "development"
}
godotenv.Load(".env." + env + ".local")
if "test" != env {
  godotenv.Load(".env.local")
}
godotenv.Load(".env." + env)
godotenv.Load() // 原始 .env

功能完整性声明

该库已被声明为功能完整 。不再接受添加新功能或破坏库 API 的 issue 或 pull request。

平台支持

Linux 和 Windows 环境都有测试覆盖和 CI,但不保证命令行版本在 Windows 上正常工作。

Notes

该库的实现核心在 godotenv.go 和 parser.go 文件中,其中 parseBytes() 函数负责实际的解析工作 。库支持变量替换(如 ${VAR} 或 $VAR)和特殊字符转义。所有代码更改都需要测试和对等 dotenv 实现的参考。